Functions for verifying signatures and MACs
This section describes PKCS#11 functions for verifying signatures and MACs.
C_VerifyInit
This function operates as specified in PKCS#11.
If the CKF_LOGIN_REQUIRED
flag is set for the Token associated with the provided session the session state must be either CKS_RW_USER_FUNCTIONS
or CKS_RO_USER_FUNCTIONS
,otherwise the error CKR_USER_NOT_LOGGED_IN
is returned.
If the object referenced by the hKey parameter has the CKA_USAGE_COUNT
attribute its value is incremented by this function.
ProtectToolkit-C also allows that hKey can specify a certificate object in place of a public key. In this case the certificate object is verified with the algorithm below. If this verification succeeds the session is initialized using the public key stored in the certificate. If the verification fails CKR_INVALID_KEY
is returned and the session is not initialized. Further the certificate object’s CKA_TRUST_LEVEL
is updated to indicate that the verification has failed.
To perform the certificate verification the object’s CKA_TRUSTED is checked. If it has the value TRUE the verification succeeds. If the attribute has the value FALSE the certificate is validated.
For self-signed certificates (that is, where the subject and the issuer are the same) the certificate is validated if the CKA_TRUSTED
is TRUE and the certificate’s signature is correct. If CKA_TRUSTED
is FALSE for a self-signed certificate then the validation fails with CKR_CERT_NOT_VALIDATED
. If the certificate is not self-signed, a search is made for the issuer’s certificate which is the certificate whose CKA_SUBJECT
matches the CKA_ISSUER
of the current certificate. If the issuer’s certificate is not found, the verification fails. If a matching issuer’s certificate is found the verification algorithm is performed on that certificate, and if that succeeds the original certificate’s signature is verified. Issuer certificate validation will continue recursively up the certificate chain until a trusted certificate (self signed or not) is reached or a certificate in the chain fails validation for any reason including not being present.
Note
This function does not enforce certificate expiry or key usage flags store in the certificate. Rather it relies on the standard Cryptoki attributes. This function will not always fail when an inappropriate key type is supplied. For example, if a private key is supplied to the function, it may succeed. In this case, however, the C_Verify will never return CKA_OK.
Synopsis
C_VerifyInit(
CK_SESSION_HANDLE hSession,
CK_MECHANISM_PTR pMechanism,
CK_OBJECT_HANDLE hKey
);
C_Verify
This function operates as specified in PKCS#11.
Synopsis
C_Verify(
CK_SESSION_HANDLE hSession,
CK_BYTE_PTR pData,
CK_ULONG ulDataLen,
CK_BYTE_PTR pSignature,
CK_ULONG ulSignatureLen
);
C_VerifyUpdate
This function operates as specified in PKCS#11.
Synopsis
C_VerifyUpdate(
CK_SESSION_HANDLE hSession,
CK_BYTE_PTR pPart,
CK_ULONG ulPartLen
);
C_VerifyFinal
This function operates as specified in PKCS#11.
Synopsis
C_VerifyFinal(
CK_SESSION_HANDLE hSession,
CK_BYTE_PTR pSignature,
CK_ULONG ulSignatureLen
);
C_VerifyRecoverInit
This function operates as specified in PKCS#11.
-
If the
CKF_LOGIN_REQUIRED
flag is set for the Token associated with the provided session the session state must be eitherCKS_RW_USER_FUNCTIONS
orCKS_RO_USER_FUNCTIONS
,otherwise the errorCKR_USER_NOT_LOGGED_IN
is returned. -
If the object referenced by the hKey parameter has the
CKA_USAGE_COUNT
attribute its value is incremented by this function. -
If the hKey parameter refers to a certificate object this function will perform the same certificate verification as specified in the C_VerifyInit function.
Synopsis
C_VerifyRecoverInit(
CK_SESSION_HANDLE hSession,
CK_MECHANISM_PTR pMechanism,
CK_OBJECT_HANDLE hKey
);
C_VerifyRecover
This function operates as specified in PKCS#11.
Synopsis
C_VerifyRecover(CK_SESSION_HANDLE hSession,
CK_BYTE_PTR pSignature,
CK_ULONG ulSignatureLen,
CK_BYTE_PTR pData,CK_ULONG_PTR pulDataLen
);